<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0046)http://www.wincvs.org/howto/cvsdoc/cvs_12.html -->
<HTML><HEAD><TITLE>CVS--Concurrent Versions System - Keyword substitution</TITLE>
<META http-equiv=Content-Type content="text/html; charset=windows-1252"><!-- This HTML file has been created by texi2html 1.51
     from cvs.texinfo on 19 January 2000 -->
<META content="MSHTML 6.00.5730.13" name=GENERATOR></HEAD>
<BODY>Go to the <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_1.html">first</A>, <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_11.html">previous</A>, <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_13.html">next</A>, <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_24.html">last</A> section, <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html">table of contents</A>. 
<P>
<HR>

<P>
<H1><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC98" 
name=SEC98>Keyword substitution</A></H1>
<P><A name=IDX367></A><A name=IDX368></A><A name=IDX369></A></P>
<P>As long as you edit source files inside a working directory you can always 
find out the state of your files via <SAMP>`cvs status'</SAMP> and <SAMP>`cvs 
log'</SAMP>. But as soon as you export the files from your development 
environment it becomes harder to identify which revisions they are. </P>
<P>CVS can use a mechanism known as <STRONG>keyword substitution</STRONG> (or 
<STRONG>keyword expansion</STRONG>) to help identifying the files. Embedded 
strings of the form <CODE>$<VAR>keyword</VAR>$</CODE> and 
<CODE>$<VAR>keyword</VAR>:...$</CODE> in a file are replaced with strings of the 
form <CODE>$<VAR>keyword</VAR>:<VAR>value</VAR>$</CODE> whenever you obtain a 
new revision of the file. </P>
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC99" 
name=SEC99>Keyword List</A></H2>
<P><A name=IDX370></A></P>
<P>This is a list of the keywords: </P>
<DL compact>
  <DT><CODE>$Author: alexp $</CODE> 
  <DD><A name=IDX371></A>The login name of the user who checked in the revision. 
  <A name=IDX372></A>
  <DT><CODE>$Date: 2000/08/19 22:46:01 $</CODE> 
  <DD>The date and time (UTC) the revision was checked in. <A name=IDX373></A>
  <DT><CODE>$Header: /cvsroot/cvsgui/www/howto/cvsdoc/cvs_12.html,v 1.1.1.1 
  2000/08/19 22:46:01 alexp Exp $</CODE> 
  <DD>A standard header containing the full pathname of the RCS file, the 
  revision number, the date (UTC), the author, the state, and the locker (if 
  locked). Files will normally never be locked when you use CVS. <A 
  name=IDX374></A>
  <DT><CODE>$Id: cvs_12.html,v 1.1.1.1 2000/08/19 22:46:01 alexp Exp $</CODE> 
  <DD>Same as <CODE>$Header: /cvsroot/cvsgui/www/howto/cvsdoc/cvs_12.html,v 
  1.1.1.1 2000/08/19 22:46:01 alexp Exp $</CODE>, except that the RCS filename 
  is without a path. <A name=IDX375></A>
  <DT><CODE>$Name: $</CODE> 
  <DD>Tag name used to check out this file. The keyword is expanded only if one 
  checks out with an explicit tag name. For example, when running the command 
  <CODE>cvs co -r first</CODE>, the keyword expands to <SAMP>`Name: 
  first'</SAMP>. <A name=IDX376></A>
  <DT><CODE>$Locker: $</CODE> 
  <DD>The login name of the user who locked the revision (empty if not locked, 
  which is the normal case unless <CODE>cvs admin -l</CODE> is in use). <A 
  name=IDX377></A>
  <DT><CODE>$Log: cvs_12.html,v $ 
  <DT><CODE>Revision 1.1.1.1 2000/08/19 22:46:01 alexp 
  <DT><CODE>first in 
  <DT><CODE>
  <DT><CODE>Revision 1.2 2000/02/15 13:16:25 shh 
  <DT><CODE>*** empty log message *** 
  <DT><CODE></CODE>
  <DD>The log message supplied during commit, preceded by a header containing 
  the RCS filename, the revision number, the author, and the date (UTC). 
  Existing log messages are <EM>not</EM> replaced. Instead, the new log message 
  is inserted after <CODE>$Log: cvs_12.html,v $ message is inserted after 
  <CODE>Revision 1.1.1.1 2000/08/19 22:46:01 alexp message is inserted after 
  <CODE>first in message is inserted after <CODE>message is inserted after 
  <CODE>Revision 1.2 2000/02/15 13:16:25 shh message is inserted after <CODE>*** 
  empty log message *** message is inserted after <CODE></CODE>. Each new line 
  is prefixed with the same string which precedes the <CODE>$Log</CODE> keyword. 
  For example, if the file contains <PRE>  /* Here is what people have been up to:
   *
   * $Log: cvs_12.html,v $
   * Revision 1.1.1.1  2000/08/19 22:46:01  alexp
   * first in
   *
   * Revision 1.2  2000/02/15 13:16:25  shh
   * *** empty log message ***
   *
   * Revision 1.1  1997/01/03 14:23:51  joe
   * Add the superfrobnicate option
   *
   */
</PRE>then additional lines which are added when expanding the 
  <CODE>$Log</CODE> keyword will be preceded by <SAMP>` * '</SAMP>. Unlike 
  previous versions of CVS and RCS, the <STRONG>comment leader</STRONG> from the 
  RCS file is not used. The <CODE>$Log</CODE> keyword is useful for accumulating 
  a complete change log in a source file, but for several reasons it can be 
  problematic. See section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_12.html#SEC103">Problems with the 
  $Log: cvs_12.html,v $ See section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_12.html#SEC103">Problems with the 
  Revision 1.1.1.1 2000/08/19 22:46:01 alexp See section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_12.html#SEC103">Problems with the 
  first in See section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_12.html#SEC103">Problems with the 
  See section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_12.html#SEC103">Problems with the 
  Revision 1.2 2000/02/15 13:16:25 shh See section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_12.html#SEC103">Problems with the 
  *** empty log message *** See section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_12.html#SEC103">Problems with the 
  keyword.</A>. <A name=IDX378></A>
  <DT><CODE>$RCSfile: cvs_12.html,v $</CODE> 
  <DD>The name of the RCS file without a path. <A name=IDX379></A>
  <DT><CODE>$Revision: 1.1.1.1 $</CODE> 
  <DD>The revision number assigned to the revision. <A name=IDX380></A>
  <DT><CODE>$Source: /cvsroot/cvsgui/www/howto/cvsdoc/cvs_12.html,v $</CODE> 
  <DD>The full pathname of the RCS file. <A name=IDX381></A>
  <DT><CODE>$State: Exp $</CODE> 
  <DD>The state assigned to the revision. States can be assigned with <CODE>cvs 
  admin -s</CODE>---see section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_16.html#SEC120">admin 
  options</A>. </DD></DL>
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC100" 
name=SEC100>Using keywords</A></H2>
<P>To include a keyword string you simply include the relevant text string, such 
as <CODE>$Id: cvs_12.html,v 1.1.1.1 2000/08/19 22:46:01 alexp Exp $</CODE>, 
inside the file, and commit the file. CVS will automatically expand the string 
as part of the commit operation. </P>
<P>It is common to embed the <CODE>$</CODE>Id$ string in the source files so 
that it gets passed through to generated files. For example, if you are managing 
computer program source code, you might include a variable which is initialized 
to contain that string. Or some C compilers may provide a <CODE>#pragma 
ident</CODE> directive. Or a document management system might provide a way to 
pass a string through to generated files. </P>
<P><A name=IDX382></A>The <CODE>ident</CODE> command (which is part of the RCS 
package) can be used to extract keywords and their values from a file. This can 
be handy for text files, but it is even more useful for extracting keywords from 
binary files. </P><PRE>$ ident samp.c
samp.c:
     $Id: cvs_12.html,v 1.1.1.1 2000/08/19 22:46:01 alexp Exp $
$ gcc samp.c
$ ident a.out
a.out:
     $Id: cvs_12.html,v 1.1.1.1 2000/08/19 22:46:01 alexp Exp $
</PRE>
<P><A name=IDX383></A>SCCS is another popular revision control system. It has a 
command, <CODE>what</CODE>, which is very similar to <CODE>ident</CODE> and used 
for the same purpose. Many sites without RCS have SCCS. Since <CODE>what</CODE> 
looks for the character sequence <CODE>@(#)</CODE> it is easy to include 
keywords that are detected by either command. Simply prefix the keyword with the 
magic SCCS phrase, like this: </P><PRE>static char *id="@(#) $Id: cvs_12.html,v 1.1.1.1 2000/08/19 22:46:01 alexp Exp $";
</PRE>
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC101" 
name=SEC101>Avoiding substitution</A></H2>
<P>Keyword substitution has its disadvantages. Sometimes you might want the 
literal text string <SAMP>`$'</SAMP>Author$ to appear inside a file without CVS 
interpreting it as a keyword and expanding it into something like 
<SAMP>`$'</SAMP>Author: ceder $. </P>
<P>There is unfortunately no way to selectively turn off keyword substitution. 
You can use <SAMP>`-ko'</SAMP> (see section <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_12.html#SEC102">Substitution 
modes</A>) to turn off keyword substitution entirely. </P>
<P>In many cases you can avoid using keywords in the source, even though they 
appear in the final product. For example, the source for this manual contains 
<SAMP>`$@asis{}Author$'</SAMP> whenever the text <SAMP>`$'</SAMP>Author$ should 
appear. In <CODE>nroff</CODE> and <CODE>troff</CODE> you can embed the 
null-character <CODE>\&amp;</CODE> inside the keyword for a similar effect. </P>
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC102" 
name=SEC102>Substitution modes</A></H2>
<P><A name=IDX384></A><A name=IDX385></A><A name=IDX386></A></P>
<P>Each file has a stored default substitution mode, and each working directory 
copy of a file also has a substitution mode. The former is set by the 
<SAMP>`-k'</SAMP> option to <CODE>cvs add</CODE> and <CODE>cvs admin</CODE>; the 
latter is set by the <SAMP>`-k'</SAMP> or <SAMP>`-A'</SAMP> options to <CODE>cvs 
checkout</CODE> or <CODE>cvs update</CODE>. <CODE>cvs diff</CODE> also has a 
<SAMP>`-k'</SAMP> option. For some examples, see section <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_9.html#SEC80">Handling binary 
files</A>, and section <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_5.html#SEC64">Merging and 
keywords</A>. </P>
<P>The modes available are: </P>
<DL compact>
  <DT><SAMP>`-kkv'</SAMP> 
  <DD>Generate keyword strings using the default form, e.g. 
  <CODE>$</CODE>Revision: 5.7 $ for the <CODE>Revision</CODE> keyword. 
  <DT><SAMP>`-kkvl'</SAMP> 
  <DD>Like <SAMP>`-kkv'</SAMP>, except that a locker's name is always inserted 
  if the given revision is currently locked. The locker's name is only relevant 
  if <CODE>cvs admin -l</CODE> is in use. 
  <DT><SAMP>`-kk'</SAMP> 
  <DD>Generate only keyword names in keyword strings; omit their values. For 
  example, for the <CODE>Revision</CODE> keyword, generate the string 
  <CODE>$</CODE>Revision$ instead of <CODE>$</CODE>Revision: 5.7 $. This option 
  is useful to ignore differences due to keyword substitution when comparing 
  different revisions of a file (see section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_5.html#SEC64">Merging and 
  keywords</A>). 
  <DT><SAMP>`-ko'</SAMP> 
  <DD>Generate the old keyword string, present in the working file just before 
  it was checked in. For example, for the <CODE>Revision</CODE> keyword, 
  generate the string <CODE>$</CODE>Revision: 1.1 $ instead of 
  <CODE>$</CODE>Revision: 5.7 $ if that is how the string appeared when the file 
  was checked in. 
  <DT><SAMP>`-kb'</SAMP> 
  <DD>Like <SAMP>`-ko'</SAMP>, but also inhibit conversion of line endings 
  between the canonical form in which they are stored in the repository 
  (linefeed only), and the form appropriate to the operating system in use on 
  the client. For systems, like unix, which use linefeed only to terminate 
  lines, this is the same as <SAMP>`-ko'</SAMP>. For more information on binary 
  files, see section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_9.html#SEC80">Handling binary 
  files</A>. 
  <DT><SAMP>`-kv'</SAMP> 
  <DD>Generate only keyword values for keyword strings. For example, for the 
  <CODE>Revision</CODE> keyword, generate the string <CODE>5.7</CODE> instead of 
  <CODE>$</CODE>Revision: 5.7 $. This can help generate files in programming 
  languages where it is hard to strip keyword delimiters like 
  <CODE>$</CODE>Revision: $ from a string. However, further keyword substitution 
  cannot be performed once the keyword names are removed, so this option should 
  be used with care. One often would like to use <SAMP>`-kv'</SAMP> with 
  <CODE>cvs export</CODE>---see section <A 
  href="http://www.wincvs.org/howto/cvsdoc/cvs_16.html#SEC132">export--Export 
  sources from CVS, similar to checkout</A>. But be aware that doesn't handle an 
  export containing binary files correctly. </DD></DL>
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC103" 
name=SEC103>Problems with the $Log: cvs_12.html,v $ 
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC103" 
name=SEC103>Problems with the Revision 1.1.1.1 2000/08/19 22:46:01 alexp 
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC103" 
name=SEC103>Problems with the first in 
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC103" 
name=SEC103>Problems with the 
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC103" 
name=SEC103>Problems with the Revision 1.2 2000/02/15 13:16:25 shh 
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC103" 
name=SEC103>Problems with the *** empty log message *** 
<H2><A href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html#TOC103" 
name=SEC103>Problems with the keyword.</A></H2>
<P>The <CODE>$</CODE>Log$ keyword is somewhat controversial. As long as you are 
working on your development system the information is easily accessible even if 
you do not use the <CODE>$</CODE>Log$ keyword--just do a <CODE>cvs log</CODE>. 
Once you export the file the history information might be useless anyhow. </P>
<P>A more serious concern is that CVS is not good at handling <CODE>$</CODE>Log$ 
entries when a branch is merged onto the main trunk. Conflicts often result from 
the merging operation. </P>
<P>People also tend to "fix" the log entries in the file (correcting spelling 
mistakes and maybe even factual errors). If that is done the information from 
<CODE>cvs log</CODE> will not be consistent with the information inside the 
file. This may or may not be a problem in real life. </P>
<P>It has been suggested that the <CODE>$</CODE>Log$ keyword should be inserted 
<EM>last</EM> in the file, and not in the files header, if it is to be used at 
all. That way the long list of change messages will not interfere with everyday 
source file browsing. </P>
<P>
<HR>

<P>Go to the <A href="http://www.wincvs.org/howto/cvsdoc/cvs_1.html">first</A>, 
<A href="http://www.wincvs.org/howto/cvsdoc/cvs_11.html">previous</A>, <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_13.html">next</A>, <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_24.html">last</A> section, <A 
href="http://www.wincvs.org/howto/cvsdoc/cvs_toc.html">table of contents</A>. 
</P></H2></H2></H2></H2></H2></H2></CODE></CODE></CODE></CODE></CODE></CODE></CODE></CODE></CODE></CODE></CODE></CODE></BODY></HTML>
